Configuring SSL Messaging for Tidal Explorer/Masterlink

This section discusses the procedure to configure SSL messaging between the MasterLink client and the Tidal Masters that the MasterLink client communicates with. MasterLink uses Java Messaging Service (JMS) to implement communications between the Tidal Master servers.

When SSL messaging is enabled, a Tidal Master only sends messages to and accepts messages from the servers it trusts. To authorize messaging between two servers, you must ensure that the certificate of one server is registered in the other's trust store, and vice versa. This requirement applies to all Tidal Masters using SSL and the Explorer Service Server that communicates with those Masters.

Refer to the Configuring SSL Messaging section in the Tidal Automation™ Installation Guide about Obtaining Server keys and Certificates and configuring SSL messaging for the various non-Explorer Tidal components: Primary Master, Backup Master, and Fault Monitor.

For each Tidal instance using SSL, you must have a pair of (server key and certificate) for the Primary Master server. Additionally, if the instance is in a Fault Tolerant configuration, you will require a pair of (server key and certificate) for the Backup Master and Fault Monitor servers.

In addition, a pair of (server key and certificate) will be required for the Explorer Service host server if the Explorer Service is running on a separate server to the Tidal Masters of interest.

Refer to section Generating Keys and Certificates in the Tidal Automation Installation Guide for instructions about Certificate generation for the Tidal Master servers. You can use the same procedure to create the (server key and certificate) pair for the Explorer Server, if required.

Exporting and Importing a Certificate

You must ensure that the certificates of the communicating servers are registered in each other's trust store, and vice versa.

Java Keytool provides certificate import and export options to help you accomplish this goal.

Java Keytool: Export a certificate for server alias TIDAL-PM from a key store name TIDAL-PM.jks and that has the storepass tidal97 to a file named TIDAL-PM.cer. This process should be performed for each master you will connect to.

Example: keytool -export -alias TIDAL-PM -file TIDAL-PM.cer -keystore TIDAL-PM.jks -storepass tidal97

Java Keytool : Import the certificate from the file created in the previous step to a keystore store named Tidal_keystore.jks that has a store password tidal97.

Example: keytool -import -v -trustcacerts -alias TIDAL-PM -file TIDAL-PM.cer -keystore Tidal_keystore.jks -storepass tidal97

TrustStores and KeyStores

A TrustStore is typically used to store certificates from trusted Certificate Authorities (CA), while a KeyStore is used to store private key and own identity certificate. For simplicity’s sake, we can use the same keystore for both purposes. In these examples, we will use a combined keystore located in the file C:\keystores\Tidal_keystore.jks.

Note: Explorer/Masterlink requires that all Tidal Master certificates are stored in a single truststore. This truststore must contain the certs for every Tidal Master using SSL that the Masterlink is required to communicate with.

Configuring SSL on the Explorer/MasterLink Server

  1. Confirm that the Explorer Server Cert created by Keytool has been imported into the truststores used by every Tidal Master enabled for SSL that MasterLink is required to communicate with.

  1. Confirm that the TrustStore in C:\keystores\Tidal_keystore.jks contains the certs created by Keytool for every Tidal Master using SSL that the Masterlink is required to communicate with as well as the Keytool created Explorer Server Cert and Key.

  2. Stop the Explorer Service.

  3. Use a text editor to open the property file explorer.props located in the Explorer\config directory.

    Note: It is suggested that you back up this file before editing it to retain the original version of the file, if needed.

  1. Locate the segment of SSL properties that looks like this in the editor:

    Note: The passwords shown in the example below are encrypted based on a password of tidal97 used in this example.

    Example: MessageBroker.SSL.enabled=YMessageBroker.SSL.keyStore=C:\keystores\Tidal_keystore.jks
    MessageBroker.SSL.keyStorePassword=aVzK:@FU@WYWAKF
    MessageBroker.SSL.keyPassword=aVzK:@FU@WYWAKF
    MessageBroker.SSL.trustStore=C:\keystores\Tidal_keystore.jks
    MessageBroker.SSL.trustStorePassword=aVzK:@FU@WYWAKF

    If such segments can't be found, manually insert the lines.

    Here is a list of each property and what it does.

    Property

    Description

    MessageBroker.SSL.enabled

    Determines whether to activate other SSL properties and enable SSL messaging. Value 'Y' means yes, and 'N' means no. You can use this property switch between SSL and non-SSL messaging modes.

    MessageBroker.SSL.keyStore

    Path to the keystore.

    MessageBroker.SSL.keyStorePassword

    Password needed to open the keystore.

    MessageBroker.SSL.keyPassword

    Password needed to read the key, if it's different from the password of the keystore.

    MessageBroker.SSL.trustStore

    Path to the truststore.

    MessageBroker.SSL.trustStorePassword

    Password needed to open the truststore.

  1. Encrypt the passwords before storing them in the property files. Refer to the section below for information about Securing Keystore Passwords for Tidal Explorer Masterlink.

  1. Save the explorer.props file.

  2. Run the Tidal Explorer Admin tool.

    • Ensure the SSL toggle switches are enabled for all Tidal instances that are configured for SSL messaging

    • Save the Explorer config if SSL toggle switched settings were modified.

  3. Start the Explorer Service.

Securing Keystore Passwords for Tidal Explorer Masterlink

Perform these steps if you are configuring SSL on Tidal Explorer:

To encrypt SSL passwords for Tidal Explorer:

  1. Open a command shell window and change directory to the lib directory under the Explorer Installation directory.

  2. Issue the commands, using tidal97 as the password in this example:

    Example: java -cp MasterLink.jar com.tidalsoft.framework.util.Pwd tidal97 @t0wwa]!S<OHXAXWK

  3. Copy the entire line of the command output and paste it into the relevant password value field of the explorer.props file.

  4. Here is the full example of the resulting explorer.props file:

# MasterLink config for integrated sign on authentication
JVMARGS=-Xms2g -Xmx4g
JAVA_HOME=C:\Java\jdk-17
MessageBroker.SSL.enabled=Y
MessageBroker.SSL.keyStore=C:\\keystores\\Tidal_keystore.jks
MessageBroker.SSL.keyStorePassword=@t0wwa]!S<OHXAXWK
MessageBroker.SSL.keyPassword=@t0wwa]!S<OHXAXWK
MessageBroker.SSL.trustStore=C:\\keystores\\Tidal_keystore.jks
MessageBroker.SSL.trustStorePassword=@t0wwa]!S<OHXAXWK

Troubleshooting Explorer/Tidal SSL Configurations

Note: The Explorer Service must be restarted to detect changes made to the SSL properties defined in the explorer.props file or changes to a Tidal Instances SSL settings made via the Explorer Admin Config Editor. This is be resolved in a future release.